---
sidebar_label: Troubleshooting ACME integration
description: Troubleshoot problems with ACME clients and OpenBao PKI Secrets Engine's ACME server.
---

# Troubleshoot PKI Secrets Engine and ACME

Solve common problems related to ACME client integration with OpenBao PKI
Secrets Engine's ACME server.

## Error: Unable to register an account with the ACME server

### Symptoms

When registering a new account without an [External Account Binding
(EAB)](/api-docs/secret/pki#acme-external-account-bindings), the
OpenBao Server rejects the request with a response like:

> Unable to register an account with ACME server

with further information provided in the debug logs (in the case of
`certbot`):

> Server requires external account binding.

or, if the client incorrectly contacted the server, an error like:

> The request must include a value for the 'externalAccountBinding' field

In either case, a new account needs to be created with an EAB token created
by OpenBao.

### Cause

If a server has been updated to require `eab_policy=always-required` in the
[ACME configuration](/api-docs/secret/pki#set-acme-configuration),
new account registration (and reuse of existing accounts will fail).

### Resolution

Using an OpenBao token, [fetch a new external account
binding](/api-docs/secret/pki#get-acme-eab-binding-token) for
the [desired directory](/api-docs/secret/pki#acme-directories):

```
$ bao write -f pki/roles/my-role-name/acme/new-eab
...
directory roles/my-role-name/acme/directory
id        bc8088d9-3816-5177-ae8e-d8393265f7dd
key       MHcCAQE... additional data elided ...
...
```

Then pass this new EAB token into the ACME client. For example, with
`certbot`:

```
$ certbot [... additional parameters ...] \
    --server https://cluster-b.openbao.example.com/v1/pki/roles/my-role-name/acme/directory \
    --eab-kid bc8088d9-3816-5177-ae8e-d8393265f7dd \
    --eab-hmac-key MHcCAQE... additional data elided ...
```

Ensure that the ACME directory passed to the ACME client matches that
fetched from the OpenBao.

## Error: Failed to verify eab

### Symptoms

When initializing a new account against this OpenBao server, the ACME client
might error with a message like:

> The client lacks sufficient authorization :: failed to verify eab

This is caused by requesting an EAB from a directory not matching the
one the client used.

### Cause

If an EAB account token is incorrectly used with the wrong directory, the
ACME server will reject the request with an error about insufficient
permissions.

### Resolution

Ensure the requested EAB token matches the directory. For a given directory
at `/some/path/acme/directory`, fetch EAB tokens from
`/some/path/amce/new-eab`. The remaining resolution steps are the same as
for [debugging account registration
failures](#debugging-account-registration-failures).

## Error: ACME validation failed for `{challenge_id}`

### Symptoms

When viewing the OpenBao server logs or attempting to fetch a certificate via
an ACME client, an error like:

> ACME validation failed for a465a798-4400-6c17-6735-e1b38c23de38-tls-alpn-01: ...

indicates that the server was unable to validate this challenge accepted
by the client.

### Cause

OpenBao can not verify the server's identity through the client's requested
[challenge type](/api-docs/secret/pki#acme-challenge-types) (`dns-01`,
`http-01`, or `tls-alpn-01`). OpenBao will not issue the certificate requested
by the client.

### Resolution

Ensure that DNS is configured correctly from the OpenBao server's perspective,
including setting [any custom DNS resolver](/api-docs/secret/pki#dns_resolver).

Ensure that any firewalls are set up to allow OpenBao to talk to the relevant
systems (the DNS server in the case of `dns-01`, port 80 on the target
machine for `http-01`, or port 443 on the target machine for `tls-alpn-01`
challenges).

## Error: The client lacks sufficient authorization: account in status: revoked

### Symptoms

When attempting to renew a certificate, the ACME client reports an error:

> The client lacks sufficient authorization: account in status: revoked

### Cause

If you run a [manual tidy](/api-docs/secret/pki#tidy_acme) or have
[auto-tidy](/api-docs/secret/pki#configure-automatic-tidy) enabled
with `tidy_acme=true, OpenBao will periodically remove stale ACME accounts.

Connections from clients using removed accounts will be rejected.

### Resolution

Refer to the ACME client's documentation for removing cached local
configuration and setup a new account, specifying any EABs as required.

## Get help

Please provide the following information when
filing a GitHub issue to help with our investigation and reproducibility:

 - ACME client name and version
 - ACME client logs and/or output
 - OpenBao server **DEBUG** level logs

## API

The PKI secrets engine has a full HTTP API. Please see the
[PKI secrets engine API](/api-docs/secret/pki) for more
details.
